<body>
Generate a postfix (reverse polish) expression from a string infix expression.
<P>
The purpose of this package is to generate a postfix (reverse polish) expression from an infix expression. The resulting postfix
expression is designed be used by a code generator for rapid evaluatoin. 
Roughly, all this package does is:
<UL>
<LI>Verify that an expression is legal infix.</LI>
<LI>Genenerate an postfix expression that a code generator can use 
(example: {@link com.tripos.common.parser.infix.PostfixEvaluator}).</LI>
</UL>
<P>
Postfix is used because of the speed at which it can be evaluated and ease in which it can be traversed.
<P>
Though the grammar support by the parser is defined below, several important charactistics to note are:
<UL>
<LI>Any identifiers that appear in an infix expression will be passed unchanged to the resulting postfix expression.
It is the job of a code generator (or evaluator) to provide values for identifiers at execution time.
<LI>Any function names that appear in an infix expression will be passed unchanged to the resulting postfix expression.
It is the job of the code generator (or evaluator) to provide an implementation (or throw an error if the function is
not defined).
</UL>
<P>
A good question to ask at this point is "Why these restrictions?". The infix parser knows how to parse 
infix AND NOTHING ELSE because different types of code generators are often required.
<UL>
<LI>If the backing store for a data model is Oracle, a code generator will likely take the parsed infix and
transform it into SQL code (to allow execution using the Oracle engine). Suppose the infix expression was
"MW &gt; 130.0 and MW &lt; 158.0" and the Oracle data set has 100,000 records. Having Oracle evaluate the expression
and fetch matching records is a lot more efficient that fetching 100,000 records and applying the filter locally.
The code generator would turn the postfix expression into something like:
<blockquote>
<pre>

SELECT CPD.structure, PROP.molecular_weight
FROM tbl_cpds CPD, tbl_cpd_props PROP
WHERE
	CPD.compound_id = PROP.compound_id
	AND PROP.molecular_weight > 130.0
	AND PROP.molecular_weight < 158.0
	
</pre>
</blockquote>
<LI>If the backing store for a data model is an in memory spreadsheet, a code generator that evaluates the postfix
expression is memory would be ideal (in fact, one is provided for you -- 
see {@link com.tripos.common.parser.infix.PostfixEvaluator}). In this case the generated code may look something like:
<blockquote>
<pre>

;;
;; Parse the expression first
;;

InfixParser parser = new InfixParser();
IParsedExpression expr = parser.parse( "MW &lt; 130.0 and mw &gt; 158.0" );

;;
;; Evaluate the expression by traversing each row of the spreadsheet, fetching the MW of
;; the row, and calling a postfix evaluator.
;;
PostfixEvaluator engine = new PostfixEvaluator();
HashMap&lt;String,Object&gt; variables = new HashMap&lt;String,Object&gt;();

for( ISpreadsheetRow row : spreadsheet ) {
	variables.put( "MW", row.getValue("MW"));
	boolean answer = engine.evalBoolean( expr, variables);
	
	if( answer ) {
		;; Do something
	}
}


</pre>
</blockquote>
</UL>
<P>

The grammar for an expression is basic infix (e.g. just like java expressions). Java operator preference is followed.
<blockquote>
<pre>
Expression      => Token
                |  Token Operator Expression
                |  UnaryOperator Expression
                |  ( Expression )
                
UnaryOperator   => NOT
				|  !
				|  -  // Unary minus
				
Operator        => LogicOperator
                |  MathOperator
                |  CompareOperator
                
LogicOperator   => AND
                |  OR
                |  &&
                |  ||
                
MathOperator    => +
                |  -
                |  *
                |  /
                |  %
                |  MOD
                
CompareOperator => ==
                |  =
                |  >
                |  >=
                |  <
                |  <=
                |  !=
                |  <>
                
Token           => Number
                |  String // Single or double quotes. Use backslah to escape.
                |  Identifier
                |  FunctionCall

FuntionCall     => Identifier()
                |  Identifer( ArgumentList )
                
ArgumentList    => Expression
                |  ArgumentList , Expression
</pre>
</blockquote>

<P>
Both function names and identifiers must follow the java naming rules ([A-Z][A-Z0-9_]+).
<P>
Example Infix Expressions:
<UL>
<LI>A > 5 AND B == 2</LI>
<LI>substring(C, 1, 4) == "greg"
<LI>uppercase(substring(C, 1, 4)) == "GREG"
<LI> ((A+B)/C + D)%15
</UL>
<P>
The postfix generated by this package can be easily evaluated (if you need a tutorial recall that postfix is a stack based
notation that eliminates parenthesis and operator precedence issues. Example infix to postfix:
<UL>
<LI> A + B ==> A B +</LI>
<LI> A + B*C => A B C * +</LI>
</UL>
</P>
</body> 